home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 1998 March / Macworld (1998-03) (Disk 1).dmg / Shareware World / Info / For Developers / GhostScript 5.10 / MacGS-510 / doc / lib.txt < prev    next >
Text File  |  1996-12-24  |  14KB  |  364 lines
  1.    Copyright (C) 1989, 1996 Aladdin Enterprises.  All rights reserved.
  2.   
  3.   This file is part of Aladdin Ghostscript.
  4.   
  5.   Aladdin Ghostscript is distributed with NO WARRANTY OF ANY KIND.  No author
  6.   or distributor accepts any responsibility for the consequences of using it,
  7.   or for whether it serves any particular purpose or works at all, unless he
  8.   or she says so in writing.  Refer to the Aladdin Ghostscript Free Public
  9.   License (the "License") for full details.
  10.   
  11.   Every copy of Aladdin Ghostscript must include a copy of the License,
  12.   normally in a plain ASCII text file named PUBLIC.  The License grants you
  13.   the right to copy, modify and redistribute Aladdin Ghostscript, but only
  14.   under certain conditions described in the License.  Among other things, the
  15.   License requires that the copyright notice and this notice be preserved on
  16.   all copies.
  17.  
  18. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  19.  
  20. This file, lib.txt, describes the Ghostscript library, a collection of C
  21. procedures that implement the primitive graphic operations of the
  22. Ghostscript language.
  23.  
  24. For an overview of Ghostscript and a list of the documentation files, see
  25. README.
  26.  
  27. ********
  28. ******** The Ghostscript library ********
  29. ********
  30.  
  31. Ghostscript is actually two programs: a language interpreter, and a graphics
  32. library.  The library provides, in the form of C procedures, all the
  33. graphics functions of the language, i.e., approximately those facilities
  34. listed in section 8.1 of the PostScript Language Reference Manual, Second
  35. Edition, starting with the graphics state operators.  In addition, the
  36. library provides some lower-level graphics facilities that offer higher
  37. performance in exchange for less generality.
  38.  
  39. PostScript operator API
  40. -----------------------
  41.  
  42. The highest level of the library, which is the one that most clients will
  43. use, directly implements the PostScript graphics operators with procedures
  44. named gs_XXX, e.g., gs_moveto, gs_fill.  Nearly all of these procedures take
  45. a graphics state object as their first argument, e.g.,
  46.     int gs_moveto(gs_state *, double, double);
  47.  
  48. Nearly all procedures return an integer code which is >= 0 for a successful
  49. return or <0 for a failure.  The failure codes correspond directly to
  50. PostScript errors, and are defined in gserrors.h.
  51.  
  52. The library implements all the operators in the following sections of the
  53. PostScript Language Reference Manual, Second Edition, with the indicated
  54. omissions and with the APIs defined in the indicated .h files.  A header of
  55. the form A.h(B.h) indicates that A.h is included in B.h, so A.h need not be
  56. included explicitly if B.h is included.  Operators marked with * in the
  57. Omissions column are not implemented directly; the library provides
  58. lower-level procedures that can be used to implement the operator.
  59.  
  60. There are slight differences in the operators that return multiple values,
  61. since C's provisions for this are awkward.  Also, the control structure for
  62. the operators involving (a) callback procedure(s) (pathforall, image,
  63. colorimage, imagemask) is partly inverted: the client calls a procedure to
  64. set up an enumerator object, and then calls another procedure for each
  65. iteration.  The ...show operators, charpath, and stringwidth also use an
  66. inverted control structure.
  67.  
  68. Section        Headers            Omissions
  69. -------        -------            ---------
  70.  
  71. Graphics State Operators --
  72. Device Independent
  73.         gscolor.h(gsstate.h)
  74.         gscolor1.h
  75.         gscolor2.h
  76.         gscspace.h
  77.         gshsb.h
  78.         gsline.h(gsstate.h)
  79.         gsstate.h
  80.  
  81. Graphics State Operators --
  82. Device Dependent
  83.         gscolor.h(gsstate.h)
  84.         gscolor1.h
  85.         gscolor2.h
  86.         gsht.h(gsht1.h,gsstate.h)
  87.         gsht1.h
  88.         gsline.h(gsstate.h)
  89.  
  90. Coordinate System and
  91. Matrix Operators
  92.         gscoord.h        *matrix, *identmatrix,
  93.         gsmatrix.h          *concatmatrix, *invertmatrix
  94.  
  95. Path Construction Operators
  96.         gspath.h        *arct, *pathforall,
  97.         gspath2.h          ustrokepath, uappend, upath, ucache
  98.  
  99. Painting Operators
  100.         gsimage.h        *image, *colorimage, *imagemask,
  101.         gspaint.h          ufill, ueofill, ustroke
  102.         gspath2.h
  103.  
  104. Form and Pattern Operators
  105.         gscolor2.h        execform
  106.  
  107. Device Setup and Output
  108. Operators
  109.         gsdevice.h        *showpage, *set/currentpagedevice
  110.  
  111. Character and Font Operators
  112.         gschar.h        *(all the show operators),
  113.         gsfont.h          definefont, undefinefont,
  114.                       findfont, *scalefont, *makefont,
  115.                       selectfont, [Global]FontDirectory,
  116.                       Standard/ISOLatin1Encoding,
  117.                       findencoding
  118.  
  119. << -------------------------------- end -------------------------------- >>
  120.  
  121. The following procedures in the above list operate differently from their
  122. PostScript operator counterparts:
  123.  
  124. Procedure(header)    Difference(s)
  125. -----------------    -------------
  126.  
  127. gs_makepattern(gscolor2.h)
  128.             Takes an explicit current color, rather than using
  129.             the current color in the graphics state.
  130.             Takes an explicit allocator for allocating the
  131.             pattern implementation.  See below for more details
  132.             on gs_makepattern.
  133.  
  134. gs_setpattern(gscolor2.h)
  135. gs_setcolor(gscolor2.h)
  136. gs_currentcolor(gscolor2.h)
  137.             Use gs_client_color rather than a set of color
  138.             parameter values.  See below for more details on
  139.             gs_setpattern.
  140.  
  141. gs_currentdash_length/pattern/offset(gsline.h)
  142.             Splits up currentdash into 3 separate procedures.
  143.  
  144. gs_screen_init/currentpoint/next/install(gsht.h)
  145.             Provide an "enumeration style" interface to
  146.             setscreen.  (gs_setscreen is also implemented.)
  147.  
  148. gs_rotate/scale/translate(gscoord.h)
  149. gs_[i][d]transform(gscoord.h)
  150.             These always operate on the graphics state CTM.
  151.             The corresponding operations on free-standing
  152.             matrices are in gsmatrix.h and have different names.
  153.  
  154. gs_path_enum_alloc/init/next/cleanup(gspath.h)
  155.             Provide an "enumeration style" implementation of
  156.             pathforall.
  157.  
  158. gs_image_enum_alloc(gsimage.h)
  159. gs_image_init/next/cleanup(gsimage.h)
  160.             Provide an "enumeration style" interface to the
  161.             equivalent of image, imagemask, and colorimage.
  162.             In the gs_image_t, ColorSpace provides an explicit
  163.             color space, rather than using the current color
  164.             space in the graphics state; ImageMask distinguishes
  165.             imagemask from [color]image.
  166.  
  167. gs_get/putdeviceparams(gsdevice.h)
  168.             Take a gs_param_list for specifying or receiving
  169.             the parameter values.  See gsparam.h for more
  170.             details.
  171.  
  172. gs_show_enum_alloc/release(gschar.h)
  173. gs_xxxshow_[n_]init(gschar.h)
  174. gs_show_next(gschar.h)
  175.             Provide an "enumeration style" interface to writing
  176.             text.  Note that control returns to the caller if
  177.             the character must be rasterized.
  178.  
  179. << -------------------------------- end -------------------------------- >>
  180.  
  181. This level of the library also implements the following operators from other
  182. sections of the Manual:
  183.  
  184. Section        Headers            Operators
  185. -------        -------            ---------
  186.  
  187. Interpreter Parameter
  188. Operators
  189.         gsfont.h        cachestatus, setcachelimit,
  190.                       *set/currentcacheparams
  191.  
  192. Display PostScript Operators
  193.         gsstate.h        set/currenthalftonephase
  194.  
  195. << -------------------------------- end -------------------------------- >>
  196.  
  197. In order to obtain the full PostScript Level 2 functionality listed above,
  198. FEATURE_DEVS must be set in the makefile to include at least the following:
  199.  
  200.   FEATURE_DEVS=patcore.dev cmykcore.dev psl2core.dev dps2core.dev ciecore.dev\
  201.     path1core.dev hsbcore.dev
  202.  
  203. The *lib.mak makefiles mentioned below do not always include all of these
  204. features.
  205.  
  206. Files named gs*.c implement the higher level of the graphics library.  As
  207. might be expected, all procedures, variables, and structures available at
  208. this level begin with gs_.  Structures that appear in these interfaces, but
  209. whose definitions may be hidden from clients, also have names beginning with
  210. gs_, i.e., the prefix reflects at what level the abstraction is made
  211. available, not the implementation.
  212.  
  213. Patterns
  214. --------
  215.  
  216. Patterns are the most complicated PostScript language objects that the
  217. library API deals with.  As in PostScript, defining a pattern color and
  218. using the color are two separate operations.
  219.  
  220. gs_makepattern defines a pattern color.  Its arguments are as follows:
  221.  
  222.     gs_client_color * -- the resulting Pattern color is stored here.
  223.       This is different from PostScript, which has no color objects per
  224.       se and hence returns a modified copy of the dictionary.
  225.  
  226.     const gs_client_pattern * -- the analogue of the original Pattern
  227.       dictionary, described in detail just below.
  228.  
  229.     const gs_matrix * -- corresponds to the matrix argument of the
  230.       makepattern operator.
  231.  
  232.     gs_state * -- the current graphics state.
  233.  
  234.     gs_memory_t * -- the allocator to use for allocating the saved data
  235.       for the Pattern color.  If this is NULL, gs_makepattern uses the
  236.       same allocator that allocated the graphics state.  Library clients
  237.       should probably always use NULL.
  238.  
  239. The gs_client_pattern structure defined in gscolor2.h corresponds to the
  240. Pattern dictionary that is the argument to the PostScript language
  241. makepattern operator.  This structure has one extra member, void
  242. *client_data, which is a place for clients to store a pointer to additional
  243. data for the PaintProc; this provides the same functionality as putting
  244. additional keys in the Pattern dictionary at the PostScript language level.
  245. The PaintProc is an ordinary C procedure that takes as parameters a
  246. gs_client_color *, which is the Pattern color that is being used for
  247. painting, and a gs_state *, which is the same graphics state that would be
  248. presented to the PaintProc in PostScript.  Currently the gs_client_color *
  249. is always the current color in the graphics state, but the PaintProc should
  250. not rely on this.  The PaintProc can retrieve the gs_client_pattern * from
  251. the gs_client_color * with the gs_getpattern procedure, also defined in
  252. gscolor2.h, and from there, it can retrieve the client_data pointer.
  253.  
  254. The normal way to set a Pattern color is to call gs_setpattern with the
  255. graphics state and with the gs_client_color returned by gs_makepattern.
  256. After that, one can use gs_setcolor to set further Pattern colors (colored,
  257. or uncolored with the same underlying color space); the rules are the same
  258. as those in PostScript.  Note that for gs_setpattern, the paint.values in
  259. the gs_client_color must be filled in for uncolored patterns; this
  260. corresponds to the additional arguments for the PostScript setpattern
  261. operator in the uncolored case.
  262.  
  263. There is a special procedure gs_makebitmappattern for creating bitmap-based
  264. patterns.  Its API is documented in gscolor2.h; its implementation, in
  265. gspcolor.c, may be useful as an example of a pattern using a particularly
  266. simple PaintProc.
  267.  
  268. Lower-level API
  269. ---------------
  270.  
  271. Files named gx*.c implement the lower level of the graphics library.  The
  272. interfaces at the gx level are less stable, and expose more of the
  273. implementation detail, than those at the gs level: in particular, the gx
  274. interfaces generally use device coordinates in an internal fixed-point
  275. representation, as opposed to the gs interfaces that use floating point user
  276. coordinates.  Named entities at this level begin with gx_.
  277.  
  278. Files named gz*.c and gz*.h are internal to the Ghostscript implementation,
  279. and are not designed to be called by clients.
  280.  
  281. A full example
  282. --------------
  283.  
  284. The file gslib.c in the Ghostscript fileset is a complete example program
  285. that initializes the library and produces output using it; files named
  286. *lib.mak (e.g., ugcclib.mak, bclib.mak) are makefiles using gslib.c as the
  287. main program.  The following annotated excerpts from this file are intended
  288. to provide a roadmap for applications that call the library.
  289.  
  290.     /* Capture stdin/out/err before gs.h redefines them. */
  291.     #include <stdio.h>
  292.     static FILE *real_stdin, *real_stdout, *real_stderr;
  293.     static void
  294.     get_real(void)
  295.     {    real_stdin = stdin, real_stdout = stdout, real_stderr = stderr;
  296.     }
  297.  
  298. Any application using Ghostscript should include the above fragment at the
  299. very beginning of the main program.
  300.  
  301.     #include "gx.h"
  302.  
  303. The gx.h header includes a wealth of declarations related to the Ghostscript
  304. memory manager, portability machinery, debugging framework, and other
  305. substrate facilities.  Any application file that calls any Ghostscript API
  306. functions should probably include gx.h.
  307.  
  308.     /* Configuration information imported from gconfig.c. */
  309.     extern gx_device *gx_device_list[];
  310.  
  311.     /* Other imported procedures */
  312.         /* from gsinit.c */
  313.     extern void gs_lib_init(P1(FILE *));
  314.     extern void gs_lib_finit(P2(int, int));
  315.         /* from gsalloc.c */
  316.     extern gs_ref_memory_t *ialloc_alloc_state(P2(gs_memory_t *, uint));
  317.  
  318. The above externs are needed for initializing the library.
  319.  
  320.         gs_ref_memory_t *imem;
  321.     #define mem ((gs_memory_t *)imem)
  322.         gs_state *pgs;
  323.         gx_device *dev = gx_device_list[0];
  324.  
  325.         gp_init();
  326.         get_real();
  327.         gs_stdin = real_stdin;
  328.         gs_stdout = real_stdout;
  329.         gs_stderr = real_stderr;
  330.         gs_lib_init(stdout);
  331.         ....
  332.         imem = ialloc_alloc_state(&gs_memory_default, 20000);
  333.         imem->space = 0;
  334.         ....
  335.         pgs = gs_state_alloc(mem);
  336.  
  337. The above code initializes the library and its memory manager.  pgs now
  338. points to the graphics state that will be passed to the drawing routines in
  339. the library.
  340.  
  341.         gs_setdevice_no_erase(pgs, dev);    /* can't erase yet */
  342.         {    gs_point dpi;
  343.             gs_screen_halftone ht;
  344.             gs_dtransform(pgs, 72.0, 72.0, &dpi);
  345.             ht.frequency = min(fabs(dpi.x), fabs(dpi.y)) / 16.001;
  346.             ht.angle = 0;
  347.             ht.spot_function = odsf;
  348.             gs_setscreen(pgs, &ht);
  349.         }
  350.  
  351. The above initializes the default device and sets a default halftone screen.
  352. (For brevity, we have omitted the definition of odsf, the spot function.)
  353.  
  354.         /* gsave and grestore (among other places) assume that */
  355.         /* there are at least 2 gstates on the graphics stack. */
  356.         /* Ensure that now. */
  357.         gs_gsave(pgs);
  358.  
  359. The above call completes initializing the graphics state.
  360.  
  361. When the program is finished, it should execute:
  362.  
  363.         gs_lib_finit(0, 0);
  364.